Mac Format 1996 April/MacFormat CD Edition MF36 (April 1996).iso/Shareware City/Developers/Tools Plus - GUI⁄Event libs/Tools Plus 2.6.1a Evaluat'n Kit/Tools Plus 2.6.1a/User Manual/03-Designing Your Application

INI File | 1995-04-01 | 24KB | 304 lines

[Display using Monaco 9]


3  Designing Your Application
`````````````````````````````





Generally, Macintosh applications follow the same basic structure outlined below.

   [1]  If your C source code file refers to any Tools Plus routines, defines, structures, or type definitions, it must have an “include” statement, such as the one below, near the beginning of the file.
        #include "ToolsPlus.h"

    If your Pascal source code file refers to any Tools Plus routines, constants, records, or types, it must have a “uses” statement, such as the one below, at the beginning of the file.  The uses statement may include other items as well.

        uses ToolsPlus

   [2]  Global Variables: Declare a global variable of TPPollRecord type.  A good name for this variable is Poll, since it’s used to poll for events.  If you want to keep your application’s global variable memory to a minimum, you can use the TPPollPointer type, which is a pointer to a polling record.

   [3]  Initialization: Your application will start by initializing the various managers in the Macintosh’s toolbox, then initializing Tools Plus

THINK C/C++ and CodeWarrior C/C++ do not perform any automatic initialization.  Therefore, it is necessary to initialize the various managers in the Macintosh toolbox before using them.  A typical application begins with the following code:
    InitGraf(&thePort);                 /*These initializing routines */
    InitFonts();                        /*  must be first lines of    */
    InitWindows();                      /*  instructions.  All        */
    InitMenus();                        /*  applications must contain */
    TEInit();                           /*  these initialization      */
    InitDialogs(0L);                    /*  routines.                 */
    SetApplLimit(value of A7 - stack size);  /* Optional routines may */
    MaxApplZone();                           /*  also be included.    */
    if (InitToolsPlus(0,5,UseColor)){   /*Tools Plus initialization   */

  CodeWarrior Pascal does not perform any automatic initialization.  Therefore, it is necessary to initialize the various managers in the Macintosh toolbox before using them.  A typical application begins with the code shown below.

  THINK Pascal performs automatic initialization if the “Initialization” compiler directive is on.  By default, the Initialization directive is on and it tells THINK Pascal to perform automatic initialization as indicated below.  If you turn the Initialization directive off by using {$I-}, you will have to initialize the various managers yourself.  The following is the source code performed by THINK Pascal’s automatic initialization.  Your application must include the last line to initialize Tools Plus.
    InitGraf(@thePort);                  {The following routines are   }
    InitFonts;                           {  part of THINK Pascal’s     }
    InitWindows;                         {  automatic initialization.  }
    InitMenus;                           {  Enter this code only if you}
    TEInit;                              {  have turned automatic      }
    InitDialogs(nil);                    {  initialization off by using}
    SetApplLimit(value of A7 - stack size);   {  the {$I-} compiler    }
    MaxApplZone;                         {  directive at the beginning }
    for i := 1 to 10 do                  {  of your application.       }
      MoreMasters;                       { End of auto-initialization. }
    if InitToolsPlus(0,5,UseColor) then  {Tools Plus initialization    }

See the InitToolsPlus routine for details on initializing Tools Plus.

Note: CodeWarrior compilers and newer versions of Symantec C/C++ support
      QuickDraw globals through a “global QuickDraw record,” so you will
      need to use qd.thePort in place of thePort in the InitGraf
      routine. This is to facilitate PowerMac compatibility.

   [4]  Initial Conditions: Your application creates its initial conditions for operation.  This includes displaying windows, opening files, etc.  These are the things your application has to do before responding to any events.

   [5]  Main Event Loop: This is where your application checks for events and responds to them.  Events are generated as a result of the user’s actions (typing, clicking, etc.) as well as system information (refresh a window, inserting a disk, etc.).  Typically, your program won’t do anything at this stage unless it’s in direct response to an event.  Tools Plus’s PollSystem routine is used to obtain an event, and to keep all of Tools Plus’s automatic processes running.  An example of a Main Event Loop is provided later in this chapter.

   [6]  Quitting: After the user quits your application, certain house cleaning should be done, such as updating and closing files.  At the very least, the wrist watch cursor should be displayed to let the user know that the Macintosh is busy while it returns to The Finder.

  If you have written Macintosh applications before, then Tools Plus will be a simple addition.  You can take an identical approach to your original programming style except that you’ll use Tools Plus’s PollSystem routine instead of the Macintosh toolbox’s GetNextEvent or WaitNextEvent routines.  You will also use Tools Plus routines to create and maintain the user interface instead of most of the Macintosh toolbox’s routines.





A Macintosh Event, in Brief
```````````````````````````
  The following is a very brief synopsis of the Toolbox Event Manager, as described in Volume I of Inside Macintosh.  The Toolbox Event Manager is the link between your application and its user.  Whenever the user types a key on the keyboard or numeric keypad, presses the mouse button, or inserts a disk in the disk drive, your application is made aware of this by means of an event.

  In addition to monitoring the user’s actions, the Toolbox Event Manager also reports other types of events that serve to inform your application as to “what is happening.”  Such an event is reported when a partially obscured window is uncovered and its contents need to be redrawn.

  The Toolbox Event Manager reports only “bare-bone” events.  When a “mouse-down” event occurs, the Event Manager reports the click’s location in the screen’s global co-ordinates, and the time of the click.  It’s up to your application to determine which window, and which object in the window was clicked.  For those who want to pursue this further, read chapter 8 (Toolbox Event) of Inside Macintosh Volume I.

Fortunately, Tools Plus events are easier to use, and are described later in this manual.





Macintosh Event Queue
`````````````````````
  As events are generated, they are placed in an event queue.  When your application is ready to process them, the oldest event is processed first.  This journaling mechanism lets the Macintosh remember a series of rapidly occurring events and store them until your application is ready to process them.

  Events have a certain priority, meaning that some events will be reported before others regardless of when they actually occurred.  Their priority is as follows:

    1.  activate/deactivate a window

    2.  mouse-down/up, key down/up, disk insert, network driver,
        application-defined events (first in first out)

    3.  auto-key (key pressed and held, causing it to repeat)

    4.  update a window (refresh a window in front-to-back order)

  The priority of events insures that illogical events are not reported.  For example, the user may click twice in a window’s “go away” box before your application gets around to processing the event.  The first click will signal your application to close the window.  The second click will not be reported as a click in a non-existent (closed) window.  The click’s location will be analyzed after the window is closed, and reported accordingly.

Warning: The event queue can store a maximum of 20 events.  If your
         application is so busy that it lets more than 20 events
         accumulate in the queue, the oldest events will be discarded
         to make room for the new ones.  This may have negative
         consequences.





Key Up Events
`````````````
  Although events are detailed in chapter 8 of Inside Macintosh Volume I, and later in this manual under “System polling,” you should be aware that key-up events are ignored.  If your application needs to be informed when a key is released, the following statement should appear in your application immediately following InitToolsPlus:

                          SetEventMask(EveryEvent);

  This SetEventMask statement tells the Event Manager to report key-up events as well as all others to your application.

  Reporting key-up events may cause problems if other applications are used prior to rebooting the Macintosh, since some applications may expect never to encounter a key-up event.  This can be resolved by executing the following statement prior to ending your application:

                    SetEventMask(EveryEvent - KeyUpMask);

  This statement will tell the operating system to respond to all events, except the key-up event.  Most applications will never need to be aware of key-up events.

Warning: Because Desk Accessories may rely on certain types of events,
         your application shouldn’t set the event mask to prevent any
         events other that key-up events.





Tools Plus Events
`````````````````
  Tools Plus events are a lot easier to use than the Macintosh’s Toolbox Event Manager’s events.  By calling Tools Plus’s PollSystem routine, the event you obtain will be translated into something that is immediately usable.  The PollSystem routine details these events later in this manual.





The Main Event Loop
```````````````````
  This manual states that the main event loop is the “heart-beat” of Tools Plus.  Without it, Tools Plus simply could not work.  The main event loop should also be the central hub of your application.  From the perspective of your application, the main event loop obtains events and responds to them appropriately.

  A typical loop would have a structure that is similar to the example below.  For now, don’t concern yourself with the contents of the polling record.  All aspects of polling are explained by the PollSystem routine.

ExitTheProgram := false;             {Boolean variable that determines }
                                     {  when your application should   }
                                     {  terminate.  Somewhere in your  }
                                     {  application, this variable will}
                                     {  be set to true when it is      }
                                     {  time to return to The Finder.  }
repeat                               {Beginning of the main event loop }
  if PollSystem(Poll) then           {Poll for an event.  If PollSystem}
    begin                            {  is true, an event occurred &   }
                                     {  ‘Poll’ has the details.        }
      case Poll.What of              {Based on the type of event you   }
                                     {  got, respond in the appropriate}
                                     {  manner…                        }
        doChgWindow:                 {Request to activate an inactive  }
                                     {  window…                        }
          MyWindowChanger(Poll);     {Do whatever your application     }
                                     {  needs to do when the user      }
                                     {  clicks an inactive window.     }
        doGoAway:                    {User clicked in a window’s close }
                                     {  box…                           }
          MyGoAway(Poll);            {Do whatever your application     }
                                     {  needs to do when the user      }
                                     {  clicks a close box.            }

        {Your event loop will process the remainder of its event types }
        {  in this area…                                               }

        otherwise                    {By excluding events you want to  }
                                     {  ignore from the CASE statement,}
                                     {  they will fall into this area  }
                                     {  and be ignored.                }
      end                            {End of ‘event type’ selection    }
    end;                             {End of responding to an event    }

  {Some sophisticated applications will do background work while they  }
  {  are polling for events.  They can perform one ‘cycle’ of their    }
  {  task at this point.                                               }

until ExitTheProgram;                {End of the main event loop.      }



  Keep in mind that this is only an example, and not a Tools Plus prerequisite.  You will probably find a main event loop that is more suitable to your own style of programming and to your application’s unique requirements.  Advanced programmers may have several event loops, depending on what your application is doing.  Note that only one event loop can be active at a time.





System 5 and 6’s Finder and MultiFinder, and System 7
`````````````````````````````````````````````````````
  There are some subtle differences between applications that run under Finder (System 5 and 6) and MultiFinder (System 5 and 6) and System 7.  Fortunately, Tools Plus runs under Finder, MultiFinder, and System 7 with minimal consideration on your part.  Please note that there is a distinction between Finder and MultiFinder when reading this manual.  There are entire chapters dedicated to the Finder and MultiFinder in other books, as well as in THINK Reference.  Here is an overview.

Finder
``````
  Prior to System 5, the Macintosh had only the Finder to present and maintain it’s desk top metaphor.  Finder lets you run only one application at a time, so your application has access to all the memory the Macintosh has available.  Desk accessories (DAs) share the same heap memory with your application, and their windows can be intermingled with windows in your application.

  When the user opens or activates a desk accessory, Tools Plus automatically modifies your menus to disable all menus and menu items that don’t pertain to the desk accessory: only the File menu’s Quit item is enabled, as are the Edit menu’s Undo, Cut, Copy, Paste and Clear items.  When the desk accessory is closed or your application’s window is activated, the menus are automatically restored to their normal settings.

  If your application has a tool bar and/or floating palettes, Tools Plus automatically creates a “Desk Accessory Layer” in which all desk accessory windows are kept together to prevent their intermingling with your application’s windows.  This is done to prevent the confusing condition that arises when the front most window is a floating palette or tool bar (belonging to your application), behind which is a desk accessory, followed by another window belonging to your application.  To the user, it may appear (erroneously) that the palette’s operations apply to the desk accessory

  Programming for the Finder is the simplest case, since you can consider your application to be always active and the only application running.

MultiFinder
```````````
  With the advent of System 5, MultiFinder made cooperative multi-tasking a reality on the Macintosh.  Cooperative, or “switched” multi-tasking as it is often called, lets several applications run simultaneously by cycling amongst all the tasks.  The term “cooperative” is used because each application must cooperate with all others by relinquishing control to give the others some processing time.

  Under MultiFinder, the user can launch and run several applications.  MultiFinder itself is an application that is always running, busily presenting and maintaining the desk top metaphor.  When an application is launched, it is allocated a finite amount of memory that is specified by its SIZE resource.

  Only one application can be active (the front most window) at a time under MultiFinder, even though, potentially, you may be able to see dozens of windows from multiple applications simultaneously.  Therefore, the active application is temporarily “suspended” when another application (or desk accessory) is activated.  Please note that suspended applications can also receive events and processing time.  Some of the SIZE resource’s settings specify how your application behaves when it is suspended or resumed.

  Tools Plus’s PollSystem routine takes care of task switching.  This includes “minor” switches in which your application gets some processing cycles then allows other applications to do the same, and “major” switches in which your application is either activated or deactivated.  PollSystem covers this topic in detail.

  Desk accessories are handled slightly differently under MultiFinder in that they don’t share memory with your application.  Instead, they inhabit the “DA layer.”  The DA layer is like a single application in which all desk accessory windows exist.  Whenever the user clicks a desk accessory, the DA layer is activated.  Tools Plus takes care of interaction with desk accessories automatically.  Whenever a desk accessory is activated, the menu bar is replaced with the DA layer’s menu bar, and your application’s tool bar and floating palettes are hidden.  Your application’s menu bar is restored when your application is activated, and the tool bar and floating palettes are displayed.

System 7
````````
  Programming for System 7 is identical to programming for MultiFinder.  Each desk accessory, however, behaves like a separate application.  Tools Plus takes care of this automatically.

Warning: All MultiFinder and System 7 compatible applications must have
         a SIZE resource.  The Completing Your Application chapter
         details the requirements of the SIZE resource.





The C Header file (ToolsPlus.h)
```````````````````````````````
  When the Macintosh was originally created, Apple made a strong commitment to Pascal as the “Language of Choice”  for Macintosh programming.  Therefore, the Macintosh’s toolbox was designed to work with Pascal calling conventions and Pascal strings.

  Fortunately, C allows you to access the Macintosh toolbox’s Pascal functions and procedures from C by declaring prototypes as having Pascal calling conventions:

            pascal void WindowTitle (short Window, Str255 Title);

  The one thing you should pay particular attention to, is Pascal strings.  In Pascal, a string is a constant or variable that is from 1 to 255 bytes in length, prefixed with an additional length byte (byte zero).  Pascal strings, unlike C strings, are not null terminated.  The Str255 structure is available in C to accommodate Pascal-style length-prefixed strings.  It is defined in the Types.h header file as:

                     typedef unsigned char Str255[256];

  When you populate a Pascal string, remember to prefix the string’s text with “\p” to indicate that it is a Pascal string.  The example below illustrates this:

                   WindowTitle (18, "\pCustomer Inquiry");

  You can use the P2CStr and C2PStr routines (defined in the pascal.h header file) to convert Pascal strings to C strings, and C strings to Pascal strings.





Range Checking
``````````````
Tools Plus has built-in parameter range checking that is always active, even when you turn off your compiler’s range checking option.  This feature is available to both C and Pascal programmers.  Although this feature adds about 1K of code and requires a very slight amount of processing time, the benefits are well worth it when you consider the time you will save during application development.

  If your application passes a parameter to a Tools Plus routine with a value that is out of the required range, an alert is displayed stating:

      Error: Parameter passed to a Tools Plus routine is not within
             the legal range of values.

  When this occurs, the Tools Plus routine does not execute.  Instead of executing the offended Tools Plus routine, an alert is displayed with the above message and a “Continue” button.  Your application will resume when the Continue button is clicked.





The Dialog Manager
``````````````````
When designing an application that uses Tools Plus libraries, avoid the Macintosh toolbox’s Dialog Manager (you may still use alerts, however).  The Dialog Manager is effective at creating simple windows, but it quickly reaches its limits when trying to implement the diversity or complexity of features available on most windows seen in today’s commercial software.

Tools Plus performs numerous tasks behind the scenes to ensure that all elements of your user interface work together seamlessly, and when the Dialog Manager is introduced into the equation, the simplicity and elegance of Tools Plus can be easily overshadowed by the Dialog Manager idiosyncrasies.

As a rule, use Tools Plus windows instead of using the Dialog Manager’s modal or modeless dialogs.





Power Macintosh Performance
```````````````````````````
  Tools Plus libraries are available in native-Power Macintosh format, meaning they have been compiled specifically to take advantage of the enhanced performance offered by a PowerPC processor.  You may notice, however, that parts of your application do not experience any performance improvements, and in some cases, native Power Macintosh applications may actually be slower than their 680x0 counterparts.

  One of the reasons for this is that significant portions of the Power Macintosh’s toolbox (written by Apple) are still made up of 680x0 code, and are therefore emulated by the PowerPC processor.  This phenomenon is similar to running a standard Macintosh application on a Power Macintosh: it works, but it’s not quick.  At the time of this writing, much of QuickDraw was being emulated on PowerPC’s, resulting in unflattering graphics performance.

  We urge you to write your applications using standard Macintosh toolbox calls in spite of the short-term performance degradation.  Doing so will help to ensure that your applications continue to run on newer Power Macintoshes (whose ROMs will surely include PowerPC-native QuickDraw), and on new PowerPC processors that will be created in the future.

  Writing your own work-arounds may result in an immediate performance improvement while sacrificing compatibility with future Power Macintoshes, or not taking advantage of improvements that will be available as the Power Mac toolbox matures.





What to read next
`````````````````
  A synopsis of each chapter can be found at the beginning of each section of this manual.  Familiarize yourself with the basic concepts in all the remaining sections before you start programming.  You may then want to learn about the intricacies of each Tools Plus routine.

  Devote considerable attention to the section on System Polling.  It explains task switching, and details each kind of event that can be reported by Tools Plus, as well as how to respond to those events.  You will be better equipped to design your application when you know what to expect from PollSystem.

  The Special Routines section lists Macintosh Toolbox routines that require special attention, in that they should be used with caution or not at all.  Using some of these routines will interfere with Tools Plus’s normal operations, whereas other routines are obsolete by Tools Plus’s wealth of services and features.

  The section on Completing Your Application is not news to Macintosh programming veterans.  It is there for the benefit of new developers to help them finish their application and make it a double-clickable program.  The SIZE resource and its required settings are detailed there.